Release 10.1A: OpenEdge Development:
Messaging and ESB

Message-reception issues

The sections that follow discuss several message-reception issues in the PTP and Pub/Sub domains.

Stopping and starting message reception

To actually start receiving messages, the 4GL application must call the startReceiveMessages procedure in the Session object. One call to the startReceiveMessages procedure is sufficient for the session. The application typically calls the startReceiveMessages procedure after subscribing to all topics of interest (in the Pub/Sub domain) or registering Message Consumer objects with the queues of interest (in the PTP domain).

The application can also call the stopReceiveMessages procedure to temporarily stop the reception of messages. To resume message reception, it can call the startReceiveMessages procedure again.

In the Pub/Sub domain, calling the stopReceiveMessages procedure does not cancel existing subscriptions; however, for any nondurable subscription, messages published while reception is stopped are not delivered.

In the PTP domain, the messages are queued while the client is in the stopReceiveMessages procedure state and are delivered to the client after the startReceiveMessages procedure is called again.

Stopping the reception of messages is recommended when an application is not going to process messages for a while. If the stopReceiveMessages procedure is not called, messages are queued in a 4GL-JMS temporary queue on the server side, potentially consuming a large amount of memory.

Note: After calling the stopReceiveMessages procedure, the 4GL client might receive one message sent from the server prior to execution of the call.

Message Consumer scope

A Message Consumer object can be used to handle only one subscription (in the Pub/Sub domain) or receive messages from only one queue (in the PTP domain).

When the deleteConsumer procedure is called, message reception is canceled and the Message Consumer object is deleted.

Notes: To delete a durable subscription (in the Pub/Sub domain), the cancelDurableSubscription procedure in pubsubsession.p or jmssession.p must be called as well, since deleteConsumer procedure only suspends the subscription in the current session. There is no equivalent to a durable subscription in the PTP domain.

It is an error to call the cancelDurableSubscription procedure while there is an active Message Consumer for that subscription. First call the deleteConsumer procedure to delete the Message Consumer.

When a Message Consumer object is used for receiving replies through the requestReply procedure call, it can be used many times; there is no need to create one for every call. The deleteSession procedure call deletes all Message Consumer objects for that session.

4GL run-time message-processing states

A 4GL application receives and processes messages when it is in an I/O-blocking state. The same rules that determine when asynchronous completion procedures are fired also determine when message handlers are called. The 4GL application should typically use the WAIT–FOR statement or the waitForMessages procedure API session call for processing messages as well as for other events.

The waitForMessages procedure is a convenient way to write message-handling code that is independent of the environment in which the 4GL application is executed (GUI, CHUI, batch, AppServer, or WebSpeed). It processes all events that occur while the application is waiting, including user-interface events and asynchronous call events, and it allows the application to specify when to stop waiting.

The waitForMessages procedure takes three input parameters: a procedure handle, the name of a user-defined function in the procedure that returns a LOGICAL value, and a timeOut parameter of type INTEGER (specifying an interval in seconds). The waitForMessages procedure waits and processes events as long as: a) the user-defined function returns TRUE; and b) the interval specified by the timeOut value elapses without any messages being received.

The user-defined function is evaluated by the 4GL-JMS API after the message handler is executed. Typically, the 4GL application should have logic for changing the return value of the function in the message handler.

Synchronous message reception

The 4GL does not explicitly support receiving messages synchronously, but the same effect can be achieved by use of the WAIT–FOR statement or the waitForMessages procedure. These constructs wait for a user-defined event. When the desired message is received, the message handler can trigger the termination of the WAIT–FOR statement or the waitForMessages procedure—for example, by applying the specified user-defined event.